Work Orders Interface Implementation Guide

Introduction

The third-party Work Orders Interface allows you to create work orders in New World ERP Utility Management, send those work orders to a third-party system to be managed and executed, and have key completion information imported back into the Tyler software.

This is accomplished with an existing standard interface that requires no custom software development by Tyler. However, the third party system will need some customization to meet New World ERP standards.

Note: The Web API must be installed BEFORE implementing the Work Orders Interface. If the Web API has not been installed, please see the Web API Installation Guide in Help Central (Applications & Maintenance > Utility Management> User Documentation > Interface Guides)

How to Use This Guide

This guide consists of the following sections: 

• Web API Services Configuration. This section describes how to configure the Web API Services, including entering the values your third-party vendor will use to authenticate themselves, and indicating whether additional credentials are required.
• Preparing for Use. This section provides guidance for process decisions related to the integration of the interface, such as deciding which work order types should be exported to the third-party system, what specific work order information should be included in the export, how to handle work order changes, and more.
• Initial Implementation and Day-to-Day Use. This section describes the day-to-day use of the Work Orders interface, such as how to configure the work order types that are exported to the third-party software, how to execute some work orders in-house, checking work order results, and more.
• Web API Test Client. This section describes how to test the interface to ensure that it is installed properly. Testing is optional.

• Third Party Integration Guide. This section provides the technical specifications for programming the interface to the third party. This section is intended for utility management and the third party’s technical staff.

Web API Services Configuration

The third party makes calls to our services. Every time they do, they pass a name and a password. That name and password must match the values entered in New World ERP. Therefore, these values must be entered in the VendorConfig.xml file, and then communicated to your vendor so they can use them.

For more information, please refer to the Web API Services Configuration section of the Web API Installation Guide.

• Update the username and password properties with values your Work Order vendor will use to authenticate themselves. These do not need to be valid network credentials or a New World ERP user. The vendor will pass user name and credentials into our APIs, our APIs will confirm the credentials against the one entered here.
• The ‘Require Logos Authorization’ option controls whether or not additional credentials are required in the HTTP request header.
• Verify that the application is set as ‘UM’ and module as ‘WorkOrder’.
• Verify that the ‘Display Name’ field is set as ‘3rd party work order’.

Web Application Setup

In Internet Information Service (IIS) Manager, expand Default Web Site and click on the Logos.WebApi node. Open Authentication and make sure only Anonymous Authentication is enabled.

HTTP Errors must be turned on in the Web Server role in Server Manager. See the screen shot below.

Preparing for Use

You will need to work with your Work Orders system vendor or a systems integrator to customize your system to New World ERP specifications. The third-party Work Order Integration Guidelines document provides technical guidance for this integration. This document provides guidance for process decisions related to the integration.

Which Work Orders

Most utilities have a number of different types of work orders. Will all work orders be exported or will some be done 'in house' in the new world Tyler software? Many utilities perform simple work orders 'in house' in the utility department, while other more complicated work orders are performed by a public works staff. Clarify which if any work order types will be done in house, and therefore not export, and which will be exported.

Work Order Class

You can have any number of work order types, but all work orders fall into eight work order Activity Types, also called work order classes for the purposes of this interface. Classes are important from an integration standpoint as the work order class determines what information is expected to complete a work order. The classes are Read, Move in Read, Turn On, Turn Off, Remove, Attach, Exchange, and Misc. For example, a utility might have work order types of read, re-read, final read, pool fill read, all of which would be of class read, and all of which would expect basic meter read information to be returned. For more information on how classes affect the interface, see the Third-Party Integration Guidelines section below.

Values to Present to Technician

The interface exports a robust set of information about the account including all its meters and the details about the meters. You need to decide what information is important to the work order technicians for the different work order types, and then work with the integrator and/or third-party work order vendor to configure the interface to consume that information and the system to present it on the work orders.

Data Mapping

Some of the value of the interface is derived from the fact that work order results are imported from the third-party work order system back into the billing system; no duplicate entry is necessary. However, many of the values in the work order results are not free form values, but rather predefined value sets. The third-party system will therefore need some sort of mapping to understand what the permissible values are for these results. Below is a list of the values with predefined lists:

• Completed by Employee - The employee that completed the work order. This is optional.
• Result Code - A list of values describing the results of the work order.
• Read Type - The type of read for work orders that collect reads.
• Meter Type - For attach work order, a new meter at the account is specified. That meter must be of a valid type. Furthermore, if you are a utility with multiple services, the third party may need to know which meter types are valid for which service classes.
• Routes - For attach work orders, the work order results expect the meter to be placed in a valid route.
• Services - The list of services you provide. This is for metered services only. If you provide multiple service classes, such as water and electric, you might want to clarify which are associated with which service class.
• Rates - The list of rates you charge. This is for metered rates only. If you provide multiple service classes, such as water and electric, you might want to clarify which are associated with which service class.

Work Order Changes

When work order changes or cancellations originate in the Tyler software, the changes or cancellations must be manually indicated in order to keep the two systems in sync.

If a work order is cancelled in the third-party system, it can be automatically canceled in New World ERP. However, if a work order type is changed in the third-party system, the results will be rejected. A manual procedure is required to handle these changes. Either results must be entered manually into New World ERP or a new work order with the proper type must be created in New World ERP, which will then flow into the third-party system to be completed.

Results Data

When work orders are completed in the third-party system, the results are imported automatically into the New World ERP Utility Management software. These work orders are marked complete and the meter reads are entered and available to Billing. There is no opportunity for Utility staff to review this information. If the Utility staff must review the information before it is posted in New World ERP, then they must do so within the third-party system as a final step, if, that is, the third-party system supports such a review. This would mean providing some utility staff access to the third-party system. This is particularly important for attach work orders, as our system expects route, rate, service, and other information that the meter tech will not likely know.

Meters Must Exist

Work orders of the Attach and Exchange classes (activity types) expect a new meter to be specified. This new meter must exist in the New World ERP software, it cannot be created on the fly. Additionally, this new meter must not already be in use on another account. If these conditions are not met, the results will be rejected.

Monitoring Errors

Errors can occur in the interface. In particular, the third-party system can try to pass in results that New World ERP considers invalid. These results will be rejected. Errors are logged in the New World ERP Interface, and likely in the third-party interface. A procedure must be in place to periodically review these errors.

Initial Implementation and Day-to-Day Use

Initial Configuration

To export work orders, you must define which work order types will be exported to the third-party software. This is done in Maintenance via the Work Order Type List page: 

Maintenance > Utility Management > Miscellaneous Definitions > Work Order Types.

On the Work Order Type List page, open one after the other, each work order type you would like to export and select the Export Through Work Order Interface check box. Be sure to click Save after setting each flag.

The Export Through Work Order Interface check box should be cleared for all work order types that should NOT be exported via the interface.

The Export Work Order column has been added to the Work Order Type List grid to make it easy to see at-a-glance which work order types are flagged for exporting to third-party software and which are not. A green check mark indicates that a work order type will be exported via the interface; the absence of a check mark indicates that the work order type will NOT be exported.

Creating Work Orders

Create work orders as you normally would. If the work order type you select is flagged to export, the work order will automatically export to the third-party system where it will be worked on and completed.

Assign/Print

Work orders flagged for exporting will be exported to the third-party system and managed and executed from there.

If you are executing some work orders in-house, you will need to be careful to only print/assign work order types that are not flagged for exporting. Both the print and assign features allow the user to select by type. Users should select only types that are not being exported. It may be desirable to establish a naming convention to aid this segregation.

As these work orders are completed in the third-party system, they will naturally be marked as complete and their results will be logged. Generally speaking, you should not use the work order results process for these work orders.

Work Order Results

The results of work orders that are exported to third-party systems will be sent to New World ERP Utilities Management automatically as the work orders are completed. For such work orders, there is no need to use the work order results option (except perhaps in very unusual situations). Once work orders are completed in the third-party system, reads will display in New World ERP, the work order will show as complete, and any appropriate action will be taken on the meter.

You can tell which work orders are complete based on the Complete Date (see below) and, if you enter into the work order, the way the information is formatted. However, no information will be available from the third-party system about the progress or timing of an incomplete work order. If this kind of information is needed, it must be accessed through the third-party software.

The screen shot above shows the Work Orders associated with a selected customer in Customer Service. The Complete Date column lists completion dates for complete work orders. Incomplete work orders display here as Open.

If you are executing some types of work orders in house, you will still use the Result feature as normal to complete those work orders.

Staging

As work orders are completed in the third-party system, they are marked as complete in New World ERP. Like any completed work order, their results cannot be directly edited or changed. This includes work orders with complex actions, such as attaching new meters and exchanging meters.

Should you wish to have utility staff review or supplement information on the work order before it is completed, you will need to provide these staff members access to the third-patty system, and configure the workflow in that system so their review is the final step to complete these work orders.

If the third-party system sends work orders that are incomplete or contain invalid information, those work orders will not be automatically completed in New World ERP. The user can search for incomplete and invalid work orders using the Third Party Only feature (check box) on the Work Orders Results page in New World ERP. They can then use the Third Party Work Order Results pop-up window to see what information was and was not passed into New World ERP. This information can be used to manually close the work order(s). For more information about this process, click here.

Reference Number

Work orders are marked complete in the third-party system and as a result the interface marks them complete in New World ERP. As they are marked complete, they are tagged with the work order number from the third-party system. This is done to add accountability and make referencing the two systems easier. You can see this reference number on the complete work order screen.

Note: Reference Number is a required field to get back in the interface.

Error Reporting

The interface provides error reporting. If the third-party system attempts to complete a work order and has provided invalid information, that work order will error out and remediation must be done manually. The error log should be periodically reviewed to determine if work orders completed in the third-party system or were not successfully imported and closed in new world ERP. For these items, the manual work order Results process should be used to complete them.

Also, the third-party or integration components probably have an error log that should be reviewed, as well.

Web API Test Client

Customers have the option of testing the interface to ensure that it is installed properly, working as it should, and ready for the third party to test and code against.

To do this, Tyler provides a tool with the product for testing the installation and querying data from the Logos WebAPI. Developers can also use this tool to validate their work.

Due to the technical nature of the following information, this section is intended for either IT personnel or administrators with strong technical knowledge.

Initial Testing

To determine the location of the package containing the test tool, do the following: 

1. Open IIS and locate the NWERP web site.
2. Right click on it and select Explore.
3. The location of the package is two levels up (the first level is the version of the package folder, the second is the package folder).

4. In the WebAPIClientTool folder, the path should be something like the following: C:\Octopus\Applications\{TENANT_NAME}\DEV\NWERP.WebAPIClientTool

^^^^Navigate to and open TestConfig.xml file in a text editor:

This XML file has a number of tests defined to ensure all features are working correctly. Ensure the fields highlighted in yellow have valid values for your environment.

AuthKey is the vendor username as configured in the Management Console file.

AuthValue is the vendor password as configured in the Management Console file.

Note: For more information, please refer to the Web API Services Configuration section of the Web API Installation Guide.

LogosID is the UM account number.

LogosPIN is the numeric part of the service address.

Launch the Web API Test Client by doing the ofllowing:  

1. Open IIS and locate the NWERP web site.
2. Right click on it and select Explore.
3. The location of the package is two levels up (the first level is the version of the package folder, the second is the package folder).

4. In the WebAPIClientTool folder, the path should be something like the following: C:\Octopus\Applications\{TENANT_NAME}\DEV\NWERP.WebAPIClientTool

running C:\Program Files (x86)\New World Systems\Logos Web API\ClientTool\Logos.WebApi.Client.exe.

Click any column in the first row to select it, and click ‘Run Selected’ button to run the test. You should see an XML formatted result in the bottom pane, similar to the image above.

Note: The tool used to test Work Orders is the same tool used to test IVR. When doing initial testing, make sure you are using the Work Order tests and not the IVR tests.

Additional Tests

The PostUtilityPayment and PostUtilityDepositPayment are disabled by default for security reasons. Initiating these tests will post a utility payment to New World ERP, and will have significant impact on a LIVE installation.

In the TestConfig.XML, ensure that the highlighted fields below are valid for your data set before testing the payment functions. Change the date to a recent bill cycle to easily review the payment in UM Customer Service.

You can choose to run all tests at once or run them individually by clicking on a test row on grid and clicking the Run Selected button. If a test fails, the row will be highlighted in red. Disabled tests are highlighted in yellow. You can enable a test by checking the TestEnabled checkbox or by changing the attribute named Active to “true” in the XML file.

Similarly you can change all values from the test tool UI and run the tests with new values. Any manual changes you make in the test tool will not be saved to the TestConfig.XML file.

Third Party Integration Guidelines

Overview

The purpose of this section is to provide a technical overview of the New World ERP (NWERP) system’s Work Order (WO) Integration APIs.

High Level Work Flow

As the following diagram suggests, there are two parts to the integration: 

New Work Orders: New World ERP WO -> 3rd party WO System: New work orders will be created in NWERP. Once created, the work order and its data fields can be periodically requested by the 3rd party WO System.

Completed Work Order: 3rd party WO System -> New World ERP WO: Once in the 3rd party WO System, work orders will be scheduled and processed. When the work orders are completed in the 3rd party WO System, the work order and data fields will be sent to NWERP where the results pertinent to meters and billing can be recorded.

General Programming Framework

The service layer will provide operations for an external system to acquire operational data from NWERP over HTTP protocol. This simple pattern supports a broad range of clients ranging from server-based systems to mobile devices. In order to request a resource, the integrator must create an HTTP request directed to the URL specified for the desired resource. NWERP will retrieve the resource at that location and return it to the requestor. The requestor is then free to use that resource without the expectation of any further interaction with NWERP.

Security Considerations

NWERP will provide valid security credentials for accessing data operations. These credentials must be provided with each resource request. New World ERP will authenticate the credentials and authorize the caller for access for the requested operation on the given resource. The API uses HTTP basic authentication.

Creating the Resource Request

Generate the resource request by sending a supported HTTP verb (GET, DELETE, and POST) to a URL that specifies the location of the resource. The URL indicates how the request will be processed. For example, the resource at api/UM/V1/WorkOrderResult/2016-00000118 would return the work order details (represented by the WorkOrder entity) for the work order with the ID 2016-00000118. An example URL for this request might be:

https://New World ERP/api/UM/V1/WorkOrder/Complete/2016-00000118

The HTTP response contains any data returned by the resource request in the body of the response. The requestor may specify the data representation of the response as either XML or JSON.

Note: All resource requests should be well formatted for XML or JSON data representation. Special characters for each data format should be escaped accordingly.

WebAPI Client Sample

The following code sample demonstrates how to request an account from the service. This code implements a .NET client written with the C# programming language. Below we have provided a sample of .NET client code with a reference for how we can use it for the endpoint specified above.

Response Body Formats

The response body returned from a resource request can be represented to the client as JSON or XML. JSON or JavaScript Object Notation is a lightweight data interchange format that can be read by both humans and computers. The data format consists of a number of name value pairs that represent the properties of an object. XML (Extensible Markup Language) is a more verbose data interchange format that consists of encoding rules that guide the use of markup and content to define an object.

application/json, text/json

An example of data represented in the JSON format.

application/xml, text/xml

An example of data represented as XML.

Error Messages

An example of an error represented as XML.

An example of an error represented as JSON.

HTTP Status Codes

A request can be answered with any of the following:

Work Order Endpoints

The Work Order API fulfills two main tasks served by their corresponding API endpoint calls:

1. Retrieve the new/updated work orders from NWERP. The calls to this endpoint(s) are GET requests that will retrieve a List<WorkOrder> entities.
2. Update the work orders that were completed in the 3rd party work order system in the NWERP system. This endpoint handles POST request which contain a WorkOrderResult entity in the body and returns a WorkOrder entity.

The Work Order API offers two different endpoints to service the first task. Depending on the 3rd party work order system choice of implementation they can be called to retrieve the new/updated work orders. The second task is serviced by one endpoint.

The format of the WorkOrder and WorkOrderResult entities is detailed in the Work Order API Resources Specifications section.

The specific endpoints and the data flow direction is presented below:

New Work Orders: New World ERP WO -> 3rd party WO System:

• Get Work Orders by Create date: api/um/v1/workorder/createddate/{startDateTime} Format of Date {YYYYMMDDTHHmm} e.g. will be api/um/v1/workorder/createddate/20170201T1420.

This endpoint will provide all the work orders created from the date specified until today’s date format.

• Get Work Order by Number: api/um/v1/workorder/number

Completed Work Order: 3rd party WO System -> New World ERP WO: Here we are expecting a work order object being passed to the work order end point.

• Update Work Order Result: api/um/v1/workorder/complete (WorkOrderResult entity passed in POST body)

Security Considerations

NWERP will provide valid security credentials for accessing data operations. All requests should be done on SSL connection.

Work Order API Resources Specification

Classes of Work Orders

Utilities define their work order types in Tyler New World ERP, and may have as many types as they wish. But all types fall into eight work order classes. These classes determine what results are expected to complete a work order.

For example, a customer might have work order types defined for a Meter Reading, Final Meter Reading, and Pool Fill Read, all of which have a class of read and expect the same data to be provided to complete the work order, the data about the meter read that was collected.

The eight classes are:

1. Read
2. Move-in Read
3. Remove
4. Attach
5. Exchange
6. Shut Off
7. Turn On
8. Miscellaneous

WorkOrderCreateDate-Specification

These are the attributes provided by the Tyler New World ERP system to the 3rd party WO system. Not all of the information provided needs to be consumed and presented on a work order; much of it is provided as context to give the work order technician additional information that may help him or her perform the work order. Consult with the Utility and Public Works Departments to understand which contextual information is desired by their organization.

The Work Order API can be called in two ways. All new and updated work orders can be requested, or a specific work order can be requested. The primary use will be to request all new work orders.

WorkOrder Entity Overview

• WorkOrder
  • Account
  • Meters: List<ServiceMeter>
    • Measurements: List<Measurement>
      • MeterReads: List<MeterRead>

WorkOrder Entity

The core values that define the work order.

Note: “Required” means it is required at the business level, so, in general, these fields are populated and will be returned.

Account Entity

The account that the work order is servicing. This information is provided for key context and supporting information for the technician. The utility should be consulted on which values are important and to be presented to the work order technician.

ServiceMeter Entity

The meters on the account. The meter marked Primary is the one for which the work order was written; basic information for this meter must be provided to the work order technician. Other meters are provided for context. Consult the utility for details on which meters and meter values should be presented.

Measurement Entity

Meters record consumption measurements at accounts. This section defines what measurements the meter records. Most utilities have water meters only, and the vast majority of water meters have one water consumption measurement on them. But some utilities will have gas or electric meters, which can have different measurement and multiple measurements.

This information is important to the technician to understand the meter they are working with, and the expected results to be returned as six of the eight work order classes expect a read in order to complete them. For these classes, reads will be expected for each measurement.

MeterRead Entity

This contains a list of historic reads for the measurement. The number of historic reads will vary based on the billing frequency and the available history, but will generally be between 0 and 13. These are meaningfully presented in chronological order.

This is optional information, but the history of the activity on the meter can often provide insight to the work order technician.

WorkOrderResult Specification

Once work orders are completed in the 3rd party system, they are returned to the Tyler New World ERP system though this API.

WorkOrderResult Entity Overview

• WorkOrderResult
  • Measurements: List<MeasurementResult>
  • NewMeter
    • NewMeterServices: List<NewMeterService>
    • NewMeterRates: List<NewMeterRate>
    • NewMeterMeasurements: List<NewMeterMeasurement>

There are a number of data entities defined for the complete work order API. As described in the Classes Of Work Orders section above, which entities require values depends on the class of the work order. Use the Class property of the WorkOrder entity returned in the retrieve API calls to determine what values must be collected from the user, and how to format your data for the work order complete call. The chart below indicates which entities are required based on the work order class.

WorkOrderResult Entity

The primary results of the work order.

Note: “Required” means that it is a required field and most of the time should be returned in the format that was return by the retrieve calls to the API.

WorkOrderResult Entity (continued)

MeasurementResult Entity

All work order classes except Attach and Miscellaneous expect a meter read returned. This is the reading of the primary meter initially passed out by the NWERP system. There must be a valid reading passed back for each measurement sent on the meter.

NewMeter Entity

Used for Attach and Exchange classes, not used for other classes. Attach represents placement of a new meter on the account. Exchange represents removal of an existing meter, replacing it with a new meter.

NewMeterService Entity

Required for work order class attach, not allowed for other classes.

NewMeterRate Entity

Required for work order class attach, optional for work order class exchange, not allowed for other classes.

NewMeterMeasurement Entity

Required for work order class attach and exchange, not allowed for other classes.

Further Documentation and Samples

After installing the NWERP Web API product, you can access additional technical help material, including JSON and XML samples, through the following link:

https://[Your_Server_Name_Here]/Logos.WebApi/Help

Replacing the placeholder with the name of the server the product was installed on.